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PREFACE 


This manual describes the operation and use of the UPDATE XVM (UPDATE) 
Utility Program. 

In this manual, it is assumed that the reader is familiar with the 
XVM/DOS system and the contents of the XVM/DOS User's Manual. 


Applicable XVM/DOS manuals useful in understanding and using UPDATE 
are the following; 


XVM/DOS Users Manual 

XVM/DOS Keyboard Command Guide 

Linking Loader XVM Utility Program Manual 

MACRO XVM Assembly Language Manual 


vii 




CHAPTER 1 


INTRODUCTION 


1.1 GENERAL DESCRIPTION 

The UPDATE XVM (UPDATE) Program provides users with the ability to 
create, examine and revise the binary library files of the XVM/DOS 
Monitor System. A library file is defined as any file containing one 
or more relocatable binary programs. The XVM/DOS Monitor's .LIBR BIN 
files, which contain the FORTRAN IV O^bject Time £ystem (OTS) routines, 
reside in the BNK and PAG System User File Directory (UFD) . 

UPDATE alters files by performing replacement, deletion, or insertion 
operations. It can also be used to create new library files, list 
the contents of libraries, and copy programs out of libraries for use 
as individual files. Figure 1-1 shows the functional relationship of 
UPDATE to its input and output files. Library creating and updating 
functions are performed by the creation of a new file from programs 
copied, on command, from either primary (original file) or secondary 
(new programs) input devices to the output device. The original file 
on the primary input device is never altered. A listing of the names 
of programs contained in the library can also be obtained. 
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Figure 1-1 

update's I/O Devices and Files 

1.2 REFERENCE MATERIAL 

The following manuals also contain information useful in understanding 
and using UPDATE: 

XVM/DOS Users Manual 

XVM/DOS Keyboard Command Guide 

Linking Loader XVM Utility Program Manual 

MACRO XVM Assembler Language Manual 

1.3 SPECIAL SYMBOLS 

Special symbols, when used in this manual, are defined as follows: 


SYMBOL 

REPRESENTS 

J 

Carriage 

RETURN - LINE FEED operation 

H 

TAB 



SPACE 


[ ] 

Optional 

Command String elements 
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CHAPTER 2 


UPDATE COMMANDS AND OPERATIONS 

2.1 LOADING PROCEDURE 

2.1.1 I/O Device Assignments 

As shown in Figure 1-1, UPDATE uses up to six .DAT slots. .DAT slots 
-2 and -3 are used by the console teleprinter and cannot be reassigned. 
The .DAT slots required by UPDATE vary with the type of operation being 
performed. For example, if a new library is to be created, only .DAT 
slots -10 (secondary input) and -15 (library file output) need be 
assigned. If a listing is also desired, then .DAT -12 must also be 
assigned. Similarly, if an update operation is to be performed where 
no programs are added and no listing is desired, then only .DAT -14 
(primary input) and .DAT -15 (library file output) need be considered. 

Because UPDATE uses the system macro .FSTAT to determine the existence 
or nonexistence of a named file, it is generally required that the 
A- version device handler be used, e.g., DTA. If only one file is to 
be open on DECtape, DTE or DTD may be used instead of DTA. 

2.1.2 Calling UPDATE 

Once the proper .DAT slot assignments have been made, UPDATE can be 
called by typing UPDATE^ after the Monitor's $. When loaded, UPDATE 
identifies itself on the console teleprinter as follows: 

UPDATE XVM Vnxnnn 
> 


and waits for a command from the user as described below. 
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2.1.3 CTRL Character Commands 

UPDATE can be restarted at any time by typing CTRL/P. The current 
operation, of course, is aborted. CTRL/C also unconditionally 
terminates UPDATE operations but returns the user to Monitor control. 

2 . 2 COMMAND DESCRIPTIONS 


update's keyboard commands are divided into three functional categories 
as follows: 

a. File Specification Commands 

b. Manipulative Commands 

c. Termination Commands 

2.2.1 File Specification Commands 

The first command to UPDATE each time it is loaded or restarted must 
be a file specification command. These commands specify the type of 
operations to be performed and the name of the file to be examined, 
modified, or created. The general form of the Command String format 
is : 


OPTION ^ FILENAME TERMINATOR 

DESIGNATOR 

Sections 2. 2. 1. 1, 2. 2. 1. 2 and 2 . 2 . 1 . 3 describe the command string 
elements . 

2. 2. 1.1 Options - The following paragraphs describe the options 
provided by UPDATE. Each option is specified in the command string 
by a single letter designator.' Table 2-1 shows legal Opt ion/ Command 
combinations . 
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Table 2-1 

Legal Option/Command Combinations 


Options ^ 

COMMANDS 

INSERT 

DELETE 

REPLACE 

FREE 

END 

CLOSE 

KILL 

U[LS] 

X 

X 

X 


X 

X 

X 

N[LS] 

X 





X 

X 

G[LS] 




X 

X 

X 

X 

L 





X 

X 

X 


^The S command is not logically useful by itself. 


U Option This option permits the updating of an existing 

library file by the deletion, insertion and replace- 
ment of the programs within it. The file to be 
upated resides on the device assigned to .DAT -14; 
programs to be inserted must be on .DAT -10; and the 
updated file is output to .DAT -15. 

N Option This option permits a new library file to be created 
from programs residing on the .DAT -10 device. The 
new library is output to .DAT -15. 

S Option The S Option causes UPDATE to remove the local 

symbol table from each program placed in the output 
file. This process shortens the length of a file by 
as much as 40%, thus conserving storage space and 
reducing library search time during loading. Non- 
library programs will occupy less memory when loaded 
with DDT XVM, since there will be no symbol table to 
load. (This is irrelevant for library programs 
because the Linking Loader and DDT do not load their 
local symbol tables. The single disadvantage of this 
option is that the removal of the symbol table pre- 
cludes symbolic debugging with DDT and DDT's opera- 
tion is then similar to DDTNS. 
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L Option This option lists the contents of the new or updated 
library output to .DAT -15 on the device assigned 
to .DAT -12. If no other options are selected, a 
listing of the named library residing on the primary 
input device (.DAT -14) can be obtained. The format 
of the listing is shown in Figure 2-1. The first 
column of the listing contains the program name. The 
second column contains the source extension and is 
output only for programs assembled under the MACRO 
XVM Assembler (which outputs loader code 330 for this 
purpose) . The third column specifies the size (in 
octal) of each program. The last column contains the 
command line echo of all Manipulative Commands 
issued, thus providing a complete log of the current 
updating operations. 

G Option This option primes UPDATE to accept the FREE Mani- 
pulative Command, which allows individual programs 
to be extracted from libraries as separate files. 



Figure 2-1 

Format of Listing File Output 
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2. 2. 1.2 Filename - A filename consists of any combination of from 1 

to 6 alphanumeric characters. The filename extension is always assumed 
to be BIN. If no filename is specified, the name .LIBR BIN is assumed 
by the program. 

2. 2. 1.3 Command Terminator - Either a Carriage RETURN (^) or an 
ALT MODE keyboard entry is used to terminate the file specification 
command. If a ^ terminator is used, control is returned to the 
UPDATE program when work on the named file is complete. If an ALT 
MODE terminator is used, control is returned to the Monitor when 
updating of the named file is complete. 

2.2.2 Manipulative Commands 

After acceptance of a file specification command, UPDATE indicates its 
readiness to accept commands for the manipulation of the contents of 
the named file by typing a > . 

In responding to the commands described below, UPDATE operates on 
library files in a sequential, program-by-program manner. Processing 
always begins at the beginning of the file (prior to the issuance of 
the first manipulative command) . All programs in a file, which are 
not deleted or replaced, are copied into the output file automatically. 
The input file is never altered. The user should exercise care in 
issuing these commands, since UPDATE has no provision for "backing 
up" in a file to manipulate a program already passed by. The user, 
therefore, should first obtain a listing (L option followed by a CLOSE) 
of the file before he attempts to modify it. 

The five manipulative commands, DELETE, REPLACE, INSERT, FREE and 
END, are described in Sections 2. 2. 2.1 through 2. 2. 2. 5. 

2. 2. 2.1 DELETE (D) Command - The D command causes the deletion of a 
named routine or a series of routines from the specified file. A 
series is specified by typing the names of the first and last routines 
of the series. The deletion is carried out by copying all the routine 
or file elements in the file up to the deleted routines into the out- 
put file and then positioning the input file just before the program 
which follows the last routine deleted. 

Form: D [ELETE],_,progl [ ,prog2] 
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The DELETE command may be used only when the U option has been re- 
quested in a file specification command. 

2. 2. 2. 2 REPLACE (R) Command - The R command causes programs in the 
original file to be replaced by new programs on the secondary input 
device. All of the programs in the original file, up to the element 
or routine to be replaced, are copied onto the output device. The 
new program (s) (replacement) is then copied onto the output file from 
a secondary input device. Upon completion, the output file is posi- 
tioned immediately after the replaced routine. 

If one program name is specified, UPDATE replaces the named program 
with a new program having the same name. If two program names are 
specified, the program with "namel" is replaced by the program with 
"name2" . 

Form: RfEPLACEl. .namel F . name2 1 

The REPLACE (R) command may be used only when the U option has been 
specified in a file specification command. 

2. 2. 2. 3 INSERT (I) Command - The I command directs UPDATE to insert 
programs contained on the secondary input device, at any point, into 
the original file as it is copied onto the output file device. On 
completion of an insert operation, the output file is positioned at a 
point immediately after the inserted program. If one name is used 

in the command, the named program is inserted into the file at the 
current position. If two names are specified, the "namel" program 
is inserted into the file after the program specified by "name2". 

Form: I [NSERT]i_iname [ ,name2] 

The I command with two names is used only when the U option has been 
previously specified in a file specification command. The I command 
with only one name can be used when either the U or N option has been 
given. 

2. 2. 2. 4 FREE (F) Command - The F command directs UPDATE to free or 
extract a named program from the library file named in a G option file 
specification command. The extracted program is transferred to the 
output device as a file of the same name. 
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Form: F [REE] i_j name 

The F command is legal only when a G option has been previously speci- 
fied in a file specification command. 

2.2.2. 5 END (E) Command - The END command causes the output file to 
be positioned at the end of the final routine of the original file. 

All remaining programs in the original file, beginning at its current 
position, are copied into the output file. The END command is a con- 
venient method of positioning the file to be modified in order that 
new routines from the secondary input may be appended to the file 
via the INSERT (I) command. 

Form: E[ND] 

The END command is logically useful only when the U option has been 
specified. 

2.2.3 UPDATE Termination Commands 

2. 2. 3.1 CLOSE (C) Command - The C command is the normal terminator 
for any of UPDATE 's operations. When used with the U option, it 
causes all of the remaining programs in the primary input file to be 
copied onto the output file starting at the current position of the 
file. When used with the N and L options, the C command closes the 
output file and completes the output of the listing file. If a file 
name is not specified with this command, the output file is given the 
name originally specified in the last file specification command. 

Form: C[LOSE] ^ [filname] 

2. 2. 3. 2 KILL (K) Command - The KILL command can be entered whenever 
UPDATE is awaiting command input and a file has been opened. When a 
new library file is being created (N option) or an old one updated 
(U option) and the KILL command is typed, the effect is as if all 
transactions prior to opening the file had not happened. Any inser- 
tions, deletions, or replacements are nullified. When a library file 
is opened, using the G option, and files are created from it using 
the FREE command, typing KILL does not delete the FREEd files, but 

it does close the library input file. To indicate that UPDATE has 


2-7 



UPDATE Commands and Operations 


restarted after a KILL command, it re-identif ies itself on the terminal, 
i.e. , 


UPDATE XVM Vnxnnn 
> 


and awaits further command input. 


Form: K[ILL] 
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CHAPTER 3 


ERROR CONDITIONS AND RECOVERY 


UPDATE performs comprehensive error checking to assure the integrity 
of the input and output files as well as correctness of operator com- 
mand strings. The program contains a large repertoire of messages 
to specifically identify the nature of the error. Table 3-1 
lists all of update's error messages accompanied by an explanation 
of each and appropriate recovery procedures. The general rule for 
recovery, particularly when an incorrect option was selected or an 
unintentional end of library file occurred, is to type CTRL/P to 
restart UPDATE; then issue a new command string. lOPS messages may 
also be printed (e.g., I0PS4 for Line Printer). 
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Table 3-1 

Update Error Messages 


Message 

Meaning 

Recovery 

FILE NOT FOUND 
COMMAND IGNORED 


The file named in an R or I command 
could not be found on the directoried 
device assigned to .DAT -10. 

Check that the device is 
properly assigned and that 
the desired file is contained 
therein. 

END OF FILE FOUND 

FILE POSITIONING COMPLET, 

PGM UNIT NOT FOUND 

The device assigned to .DAT -10 is 
nondirectoried. In attempting to 

perform an R or I command, UPDATE 
encountered either an end-of-file 
or an end-of-medium indicator in 
its first read to that device. 

Check that the paper tape is 
correctly positioned in the 
input device. With paper 
tape, this error can easily 
occur if one forgets to load 
the paper tape reader. 

EOF REACHED BY SEARCH 

COMMAND IGNORED 

The program named in an F command 
was not found in the library. 

Check that the name specified 
in the F command is correct 
and that the library does 
indeed contain the desired 
program (use L command to 
examine library) . 

END OF FILE FOUND 


The program named in an F command 
did not contain a .END statement. 

The library is contaminated. 

Obtain another copy of the 
library file and try again. 

UNRECOVERABLE READ 
.DAT -In - DYNAMIC 
where, n=J2( or 4 

ERROR ON 
KILL 

A checksum, parity or buffer over- 
flow error was detected (via the 
logical record header word 1) while 
reading from the specified input 
device. 

Obtain another version of the 
offending file and try 
again. 
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Table 3-1 (Cont.) 
UPDATE Error Messages 


Message 

Meaning 

Recovery 

NAMED FILE ALREADY ON OUTPUT 
DEVICE 

DO YOU WISH TO CONTINUE (Y/N) 

The program name specified in an 

F or C command is the same as that 
of a file residing on the .DAT -15 
(output) device. 

If a Y is typed, UPDATE 
replaces the file on the 
current file. If Y is not 
typed, UPDATE will respond 
with COMMAND IGNORED. The 
user may then type any other 
command, presumably a CLOSE 
command with another file- 
name, or abort execution of 
UPDATE and return control 
to the Monitor. If the 
latter is done, the updated 
file will be present on the 
output device with the file- 
name extension WRK. 

NOT A COMMAND 

Unrecognizable command. 

Retype the command. 

VALID ONLY IN U MODE 

COMMAND IGNORED 

A DELETE or REPLACE or an INSERT 
command (with 2 arguments) was 
issued prior to selecting the 

U option. 

Issue a new command string 
and select the U option. 

VALID ONLY WITH U OR N MODE 
COMMAND IGNORED 

An INSERT command was issued but 
neither the U nor the N option had 
been selected. 

Issue a new command string 
and select either the U or the 

N option as desired. 

VALID ONLY IN GET MODE 

COMMAND IGNORED 

A FREE command was issued but the 

G option had not been selected. 

Issue a new command string and 
select the G option. 
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Table 3-1 (Cent.) 
UPDATE Error Messages 


Message 

Meaning 

Recovery 

BUFFER OVERFLOW - DYNAMIC 

The current operation caused an 

Return to the Monitor and 

KILL 

overflow of UPDATE 's internal 
(free memory) buffer. 

assign smaller device hand- 
lers to provide more free 
memory. 

ILLEGAL COMMAND STRUCTURE 

No program name specified 

Retype command using program 

COMMAND IGNORED 

after INSERT, DELETE, REPLACE, 
or FREE command. 

name . 

BAD SECONDARY INPUT -DYNAMIC KILL 

A data error was detected during 
input from .DAT -10. 

Locate and correct the error; 
then try again. 

BAD DATA - NO PROGRAM NAME 

The file being read from the .DAT 
-10 device does not contain a 
program name (loader code 23) . 

Check that the .DAT -10 de- 
vice is the correct device 
and that the desired input 
file is there. If the above 
checks correctly, the file 
must be reassembled. 

PROGRAM NAME MISSING - DYNAMIC 

In performing a search through the 

Check that the .DAT -14 de- 

KILL 

library on the .DAT -14 device, 
the end of file was reached but no 
program name (loader code 23) could 
be found. 

vice is correctly assigned and 
that the desired input file is 
there. If the above checks 
correctly, then the library 
file is contaminated and 
must be reconstructed. 
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Table 3-1 (Cont.) 
UPDATE Error Messages 


Message 

Meaning 

Recovery 

PROGRAM NAME DISCREPANCY 

The file named in an I or R command, 
when the secondary input is from a 

If a "Y" is typed, UPDATE 
responds with "CHANGE INPUT 

FILENAME — filename 

nondirectoried device, is not the 

AND iP". If N is typed. 

PROGRAM NAME — program name 

same as the program name (loader 

UPDATE responds with: "DO 

SOURCE EXT — source extension 

DO YOU WISH TO CHANGE INPUT (Y/N) 

code 23) . 

YOU WISH TO USE FILENAME 
(Y/N)". If Y is typed, the 
filename is used, otherwise 
the program name is used. In 
either case, UPDATE will type 
SOURCE EXT WANTED and expect 
the user to respond by typing 
in a filename extension. If, 
instead, the user types only 
a Carriage RETURN, the ex- 
tension will be omitted from 
the program unit. 

PROGRAM NAME DISCREPANCY 

The file named in an I or R command 
when the secondary input is from a 

If anything other than Y is 
typed, UPDATE responds: 

FILENAME — filename 

directoried device, is not the same 

"COMMAND IGNORED". If Y is 

PROGRAM NAME — program name 
SOURCE EXT — source extension 

DO YOU WISH TO ACCEPT COMMAND 
(Y/N) 

as the program name (loader code 23) . 

typed, UPDATE replies: "DO 

YOU WISH TO USE FILENAME (Y/N)". 
If a Y is typed the filename 
is used, otherwise the program 
name is used. In either case, 
UPDATE asks: "SOURCE EXT 
WANTED". The user may then 
type a filename extension 
followed by a Carriage RETURN. 

If the user types only a Car- 
riage RETURN, the extension will 
be omitted from the program unit. 
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CHAPTER 4 


EXAMPLES USING UPDATE 


The following examples demonstrate typical command sequences using 
the various options and commands provided by UPDATE. User responses 
are underlined. 


Example 1 


To update a user created library called USRLIB: 


UPDATE XVM Vi FI 0130 
>U^U5RLIE^ 

> 1 NflMEa.. NFIME3 ^ 
: -R: NflME4, NFiriES V 
y D N AMES 


/FILE SPECIFYING COMMAND MUST BE FIRST 
/INSERT ROUTINE NAMES: AFTER NAMES 
/REPLACE ROUTINE. NAME4 WITH NAMES 
/DELETE ROUTINE NAMES FROM FILE 
.-'CLOSE USRL. I E: 


Ur'DATE X'v'M ViACiOCi 


Example 2 


To create an updated version of the system library (.LIBR) by re- 
placing the BCDIO routine: 


T Fl P R ~ 1 £i 
-T Li P D A T E 


/ASSIGN PAPERTAPE READER TO 
' S E C 0 N D A R 'r' I N F' U 7 
.-'CFlLL UPDFlT E. 


UPDATE XVM Vih00y 
>U ^ 


I:- R 5 C D 1 0 ^ 


.-'SPECIFY "UPDATE:" OPTION 
/(NOTE: LIEF: BIN ASSUMED > 

.-■REPLACE BCD 10 WITH NE.W VERSION 
.-’FROM PAPER TAPE READER 
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yc^ 


/CLiiiSE THE FILE C, LIER EIN> 
/NEW . LI BE ON . DFiT -1.5 


UPDfiTE XUM Unxnnn 
> 

To complete the update of a library file, it is necessary to use the 
PIP XVM Utility Program to delete the old library file from the .DAT 
-14 device and to transfer the new library from the .DAT -15 device 
to the .DAT -14 device. 


Example 3 


To remove all local symbols from the programs in an existing library 
and also obtain a listing; 


UPDfiTE XUM Unxnnn 

OLSt-MVNfiM^ /SELECT "LS" OPTIONS AND FILE MVNFlH BIN 

yC_^ /CLOSE TO COMPLETE OPEEhTIONS 


UPDfiTE XVM Vn;-:nnn 


Example 4 


To create a new library called LIB13, delete all local symbols and 
obtain a listing; 


UPDfiTE XVM Vn:;nnn 
> N L S'** L I S i 2 
:> I PROGl ^^ 

> I PR0G2 ^ 

y I F'RuG/ 


UPDfiTE XVM Vnxrinri 


/SELECT OPTIONS "NL: 
i' ' 1 N S E. R T F' K. ti 0 1. 
.■■*INSE'F!T PF. i.ii.'ic' rli" I E. Fi 
/IN'SE.R1 'rT',002 Fir , fc.K 
/'CLO'Sc. 1 i_i i.iuMF'L.E 1 E. 


I" FiNC' FILE LIE'iS BIN 

r r. •..iO.'i. 

Fr.i.H.i.i 

.ir'c.RriT I i-'i i :■ 
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Examples Using UPDATE 


Example 5 

To obtain copies of the BCDIO and AUXIO routines from the file .LIBRBIN 

Ur^DFlTE XVM UnKrinn 

-> F E! iJ D I U 
!> F R ij X I D 

Ur^'DATE XVM Mnxnnn 


/SELECT "13" OPTION FOR FILE . LI EE BIN 
■'EXTRACT BCDIO 
.-'EXTRACT AOXIO 
/CLOSE . LIBR BIN 
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INDEX 


$ (Monitor response) , 2-1 Keyboard commands, 2-2 

> (UPDATE response), 2-5 KILL (K) command, 2-7 


ALT MODE, 2-5 


Calling UPDATE, 2-1 
Carriage RETURN, 2-5 
Carriage RETURN - LINE FEED, 1-2 
CLOSE (C) command, 2-7 
Command/Option combination, 2-3 
Commands, 2-1 

file specification, 2-2 
keyboard, 2-2 
manipulative, 2-5 
termination, 2-7 
Command string format, 2-2 
Command terminator, 2-5 
CTRL character commands, 2-2 
CTRL/P, 3-1 


.DAT slots, 2-1 
DELETE (D) command, 2-5 
Deleting programs, 2-3 
Device assignments, 2-1 


END (E) command, 2-7 
Error conditions and recovery, 3-1 
Error messages, 3-2 
Examples, 4-1 


Filename, 2-5 

File specification commands, 2-2 
Format of command string, 2-2 
Format of listing file output, 
2-4 

FREE (F) command, 2-4, 2-6 
•FSTAT, system macro, 2-1 


G option, 2-4 


INSERT (I) command, 2-6 
Inserting programs, 2-3 
I/O device assignments, 2-1 
lOPS messages, 3-1 


Library file (definition) , 1-1 
Library file processing, 2-5 
List contents of library, 2-4 
Listing file output, format of, 
2-4 

Loading procedure, 2-1 

Log of current operations, 2-4 

L option, 2-4 


Manipulative commands, 2-5 
Memory conservation, 2-3 


New library file creation, 2-3 
N option, 2-3 


Object Time System (OTS) , 1-1 
Operations, 2-1 
Optional elements, 1-2 
Option/Command combinations, 2-3 
Options, 2-2 


Program deletion, insertion and 
replacement, 2-3 


Reference material, 1-2 
REPLACE (R) command, 2-6 
Replacing programs, 2-3 
Restarting, 2-2 


S option, 2-3 
Space, 1-2 

Symbols used in manual, 1-2 
Symbol table removal, 2-3 
System macro, .FSTAT, 2-1 


Tab, 1-2 

Terminate a command, 2-5 
Termination commands, 2-7 


U option, 2-3 

User File Directory (UFD) , 1-1 
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READER'S COMMENTS 


NOTE: This form is for document comments only. Problems 
with software should be reported on a Software 
Problem Report (SPR) form. 


Did you find errors in this manual? If so, specify by page. 


Did you find this manual understandable, usable, and well-organized? 
Please make suggestions for improvement. 


Is there sufficient documentation on associated system programs 
required for use of the software described in this manual? If not, 
what material is missing and where should it be placed? 


Please indicate the type of user/reader that you most nearly represent. 

□ Assembly language programmer 

□ Higher-level language programmer 

□ Occasional programmer (experienced) 

I I User with little programming experience 
I I Student programmer 

I I Non-programmer interested in computer concepts and capabilities 

Name Date 

Organization — — 

Street — — 

City State Zip Code 

or 

Country 

If you require a written reply, please check here. □ 
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